.. _`Mini-batch K-means Clustering`:

.. _`org.sysess.sympathy.machinelearning.mini_batch_k_means`:

Mini-batch K-means Clustering
`````````````````````````````

.. image:: dataset_blobs.svg
   :width: 48


Variant of the KMeans algorithm which uses mini-batches to reduce the computation time




Documentation
:::::::::::::

Attributes
==========

    **cluster_centers_**
        Coordinates of cluster centers.


    **inertia_**
        The value of the inertia criterion associated with the chosen
        partition if compute_labels is set to True. If compute_labels is set to
        False, it's an approximation of the inertia based on an exponentially
        weighted average of the batch inertiae.
        The inertia is defined as the sum of square distances of samples to
        their cluster center, weighted by the sample weights if provided.


    **labels_**
        Labels of each point (if compute_labels is set to True).


Definition
::::::::::


Output ports
============

    **model**  model
        Model




Configuration
=============

    **Mini-batch size** (batch_size)
        Size of the mini batches.
        For faster computations, you can set the ``batch_size`` greater than
        256 * number of cores to enable parallelism on all cores.

        .. versionchanged:: 1.0
           `batch_size` default changed from 100 to 1024.
    **Compute label assignment** (compute_labels)
        Compute label assignment and inertia for the complete dataset
        once the minibatch optimization has converged in fit.
    **Initialization method** (init)
        Method for initialization:

        'k-means++' : selects initial cluster centroids using sampling based on
        an empirical probability distribution of the points' contribution to the
        overall inertia. This technique speeds up convergence. The algorithm
        implemented is "greedy k-means++". It differs from the vanilla k-means++
        by making several trials at each sampling step and choosing the best centroid
        among them.

        'random': choose `n_clusters` observations (rows) at random from data
        for the initial centroids.

        If an array is passed, it should be of shape (n_clusters, n_features)
        and gives the initial centers.

        If a callable is passed, it should take arguments X, n_clusters and a
        random state and return an initialization.
    **Number of random samples** (init_size)
        Number of samples to randomly sample for speeding up the
        initialization (sometimes at the expense of accuracy): the
        only algorithm is initialized by running a batch KMeans on a
        random subset of the data. This needs to be larger than n_clusters.

        If `None`, the heuristic is `init_size = 3 * batch_size` if
        `3 * batch_size < n_clusters`, else `init_size = 3 * n_clusters`.
    **Maximum number of iterations** (max_iter)
        Maximum number of iterations over the complete dataset before
        stopping independently of any early stopping criterion heuristics.
    **Consecutive batches without improvement** (max_no_improvement)
        Control early stopping based on the consecutive number of mini
        batches that does not yield an improvement on the smoothed inertia.

        To disable convergence detection based on inertia, set
        max_no_improvement to None.
    **Number of clusters/centroids** (n_clusters)
        The number of clusters to form as well as the number of
        centroids to generate.
    **Number of random initializations** (n_init)
        Number of random initializations that are tried.
        In contrast to KMeans, the algorithm is only run once, using the best of
        the `n_init` initializations as measured by inertia. Several runs are
        recommended for sparse high-dimensional problems (see
        kmeans_sparse_high_dim).

        When `n_init='auto'`, the number of runs depends on the value of init:
        3 if using `init='random'` or `init` is a callable;
        1 if using `init='k-means++'` or `init` is an array-like.

        .. versionadded:: 1.2
           Added 'auto' option for `n_init`.

        .. versionchanged:: 1.4
           Default value for `n_init` changed to `'auto'` in version.
    **Random seed** (random_state)
        Determines random number generation for centroid initialization and
        random reassignment. Use an int to make the randomness deterministic.
        See random_state.
    **Reassignment ratio** (reassignment_ratio)
        Control the fraction of the maximum number of counts for a center to
        be reassigned. A higher value means that low count centers are more
        easily reassigned, which means that the model will take longer to
        converge, but should converge in a better clustering. However, too high
        a value may cause convergence issues, especially with a small batch
        size.
    **Tolerance** (tol)
        Control early stopping based on the relative center changes as
        measured by a smoothed, variance-normalized of the mean center
        squared position changes. This early stopping heuristics is
        closer to the one used for the batch variant of the algorithms
        but induces a slight computational and memory overhead over the
        inertia heuristic.

        To disable convergence detection based on normalized center
        change, set tol to 0.0 (default).









Implementation
==============

.. automodule:: node_clustering
    :noindex:

.. class:: MiniBatchKMeansClustering
    :noindex: